---
title: 页面
description: Astro 页面简介
---

import ReadMore from '~/components/ReadMore.astro';
import Since from '~/components/Since.astro'

**页面**是位于 Astro 项目的 `src/pages/` 子目录中的文件。它们负责处理路由、数据加载以及网站中每个页面的整体页面布局。

## 支持的页面文件

Astro 支持 `src/pages/` 目录中的以下文件类型：
- [`.astro`](#astro-页面)
- [`.md`](#markdownmdx-页面)
- `.mdx` (需要[安装 MDX 集成](/zh-cn/guides/integrations-guide/mdx/#安装))
- [`.html`](#html-页面)
- `.js`/`.ts` (as [endpoints](/zh-cn/guides/endpoints/))

## 基于文件的路由

Astro 使用一种名为 **基于文件的路由** 的路由策略。`src/pages/` 目录中的每个文件都会根据其文件路径成为网站上的一个端点。

一个文件也可以使用[动态路由](/zh-cn/guides/routing/#动态路由)来生成多个页面。这允许你即使内容不在特殊的 `/pages/` 目录中，也可以创建页面，例如在[内容集合](/zh-cn/guides/content-collections/)或[内容管理系统](/zh-cn/guides/cms/)中。

<ReadMore>了解更多关于 [Astro 路由](/zh-cn/guides/routing/)的内容。</ReadMore>

### 页面之间的链接

在你的 Astro 页面中，使用标准的 HTML [`<a>` 元素](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/a)来链接到网站上的其他页面。这需要使用 **相对于根域名的 URL 路径** 作为你的链接，而不是相对文件路径。

例如，要从 `example.com` 上的任何其他页面链接到 `https://example.com/authors/sonali/`，你可以像这样：

```astro title="src/pages/index.astro"
阅读更多 <a href="/authors/sonali/">关于 Sonali 的信息</a>。
```

## Astro 页面

Astro 页面使用 `.astro` 文件扩展名，并支持与 [Astro 组件](/zh-cn/basics/astro-components/)相同的功能。

```astro title="src/pages/index.astro"
---
---
<html lang="en">
  <head>
    <title>我的主页</title>
  </head>
  <body>
    <h1>欢迎来到我的网站</h1>
  </body>
</html>
```

一个页面必须生成完整的 HTML 文档。如果没有显式包含，Astro 将会自动为位于 `src/pages/` 目录下的任何 `.astro` 组件默认添加必要的 `<!DOCTYPE html>` 声明和 `<head>` 内容。你可以通过将组件标记为[局部](#局部页面)页面来为每个组件避免这种行为。

为了避免在每个页面上重复相同的 HTML 元素，你可以将常见的 `<head>` 和 `<body>` 元素移动到自己的 [布局组件](/zh-cn/basics/layouts/) 中。你可以使用任意多的布局组件。

```astro {3} /</?MySiteLayout>/
---
// src/pages/index.astro
import MySiteLayout from '../layouts/MySiteLayout.astro';
---
<MySiteLayout>
  <p>包裹在 layout 里的页面内容！</p>
</MySiteLayout>
```

<ReadMore>了解更多关于 [布局组件](/zh-cn/basics/layouts/) 的内容。</ReadMore>

## Markdown/MDX 页面

Astro 还将 `src/pages/` 目录中的任何 Markdown (`.md`) 文件视为网站中的页面。如果你安装了 [MDX 集成](/zh-cn/guides/integrations-guide/mdx/#安装)，它也会将 MDX (`.mdx`) 文件视为相同的页面。这些通常用于像博客文章和文档这样的内容丰富的页面。

[Markdown 或 MDX 页面内容的集合](/zh-cn/guides/content-collections/)可以用来[动态生成页面](/zh-cn/guides/routing/#动态路由)。

页面布局对于 [Markdown 文件](#markdownmdx-页面) 特别有用。Markdown 文件可以使用特殊的 `layout` 前置属性来指定一个 [布局组件](/zh-cn/basics/layouts/)，它将包装其 Markdown 内容在一个完整的 `<html>...</html>` 页面文档中。

```md {3}
---
# 举例：src/pages/page.md
layout: '../layouts/MySiteLayout.astro'
title: '我的 Markdown 页面'
---
# 标题

这是我的页面，使用 **Markdown** 编写。
```

<ReadMore>了解更多关于 [Astro 中的 Markdown](/zh-cn/guides/markdown-content/) 的内容。</ReadMore>

## HTML 页面

`.html` 文件扩展名的文件可以放在 `src/pages/` 中，并直接用作网站上的页面。请注意，某些关键的 Astro 功能在 [HTML 组件](/zh-cn/basics/astro-components/#html-组件) 中不受支持。

## 自定义 404 错误页面

想要自定义 404 错误页面，你可以在 `/src/pages` 中创建 `404.astro` 或 `404.md` 文件。

它将生成 `404.html` 页面。大多数[部署服务](/zh-cn/guides/deploy/)都自动找到并使用它。

## 局部页面

<p><Since v="3.4.0" /></p>

:::caution
局部页面是用于与前端库（如 [htmx](https://htmx.org/) 或 [Unpoly](https://unpoly.com/)）搭配使用的。如果你习惯编写原生的前端 JavaScript，也可以使用它。这是一项高级功能。

如果组件包含有作用域的样式或脚本，那么不应该使用局部页面，因为这些元素将从 HTML 输出中剥离；如果需要有作用域的样式，最好使用常规的非局部的页面，并配合一个知道如何将内容合并到 head 标签中的前端库。
:::

局部页面是位于 `src/pages/` 目录中的页面组件，但不会作为完整页面进行渲染。

与位于此文件夹之外的组件一样，这些文件不会自动包含 `<!DOCTYPE html>` 声明，也不会包含任何作用域样式和脚本的 `<head>` 内容。

不过，由于它们位于特殊的 `src/pages/` 目录中，所以生成的 HTML 可以通过与文件路径相对应的 URL 来访问。这允许渲染库（如 htmx、Stimulus、jQuery 等）在客户端访问它，并在页面上动态加载 HTML 的部分，而无需刷新浏览器或进行页面导航。

局部页面与渲染库结合时，局部页面提供了一种可以代替 [Astro 岛屿](/zh-cn/concepts/islands/)和 [`<script>` 标签](/zh-cn/guides/client-side-scripts/)方式用于在 Astro 中构建动态内容的方法。

可以导出值（例如`.astro`，`.mdx`）的页面文件将被标记为局部页面。

通过添加以下导出项来将 `src/pages/` 目录中的文件配置为局部页面：

```astro title="src/pages/partial.astro" ins={2}
---
export const partial = true;
---
<li>我是一个局部页面！</li>
```

`export const partial` 必须是静态标识。它可以是以下值之一：

-  布尔值 __`true`__。
-  使用 `import.meta.env` 的环境变量，如 `import.meta.env.USE_PARTIALS`。

### 和库搭配使用

 局部页面用于使用诸如 [htmx](https://htmx.org/) 的库动态更新页面的某个部分。

 下面的示例展示了将 `hx-post` 属性设置为局部页面的 URL。局部页面的内容将用于更新此页面上目标 HTML 元素的内容。

```astro title="src/pages/index.astro" 'hx-post="/partials/clicked/"'
<html>
  <head>
    <title>我的页面</title>
    <script src="https://unpkg.com/htmx.org@1.9.6"
      integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni"
      crossorigin="anonymous"></script>
  </head>
</html>
<section>
  <div id="parent-div">目标在这</div>
  <button hx-post="/partials/clicked/"
    hx-trigger="click"
    hx-target="#parent-div"
    hx-swap="innerHTML"
  >
      点我！
  </button>
</section>
```

`.astro` 局部页面必须在相应的文件路径中存在，并且包含一个导出定义将页面定义为局部页面：

```astro title="src/pages/partials/clicked.astro" {2}
---
export const partial = true;
---
<div>我被点击了！</div>
```

参见 [htmx 文档](https://htmx.org/docs/)以了解更多关于使用 htmx 的细节。
